doc/UM.txt.en_US/2.4.args-program arguments process.txt

   1
   2
   3 # arguments
   4 ===========
   5
   6     argument is a general name of cmd line paramter. actually, there are some conception of argument.
   7 @ argument, general name. it is usually seen in main function in c code. here means a paramter to program passed from cmd line.
   8 @ option, it is another way to call argument. but option is optional, append or not append some argument. so, argument like '-h' is an feature option for program, and this type of argument is called option.
   9 @ paramter, it's equal to argument, but it pay attension to the value of argument. if -f option is append to a cmd, it follows a string without '-' prefix, it's the value of -f option, and it is called paramter.
  10 @ subcmd, it is in argument, but it it is not the meaning of option and paramter. generally, it is the first argument of program in cmd line. it is used to invoking subrouting or sub-feature of a program code.
  11
  12
  13 # argument process
  14 =================
  15
  16     linux shell script provide 2 type of method to do this.
  17     first one, using builtin cmd getopts, $OPTARG is the paramter of option.
  18 ```
  19 while  getopts :f:vh opt; do
  20                 case "$opt" in
  21                         f)
  22                         echo "-f $OPTARG"
  23                         ;;
  24                         v)
  25                         ;;
  26                         h)
  27                         ;;
  28         esac
  29 done
  30 ```
  31
  32
  33 # optional paramter
  34 ================
  35
  36     but it can not process option with or without paramter. the paramter for option is optional. it is improved like this.
  37 ```
  38 while  getopts :fvh opt; do
  39         eval optstr=\${$OPTIND}
  40         case "$opt" in
  41                 f)
  42                 echo -ne "param -f and its opt $OPTARG\n"
  43
  44                 if [[ -n $optstr && ${optstr:0:1} != '-' ]]; then
  45                         echo -ne "param -f with its paramter $optstr\n"
  46                         shift
  47                 else
  48                         echo -ne "param -f without paramter."
  49                 fi
  50                 ;;
  51         esac
  52 done
  53 ```
  54
  55     another way to implement it, is using getopt cmd. it support ' :: ' operation, treat option with '::' followed as a paramter optional option. and getopt support long option with '--' prefix.
  56 ```
  57         #
  58         # paramter format translating.
  59         #  --long=a => --long a
  60         #
  61         ARGS="getopt -o f::vh -l file,version, -- $@"
  62         ARGS=`eval $ARGS`
  63
  64         # exit if failed
  65         if [[ $? != 0 ]]; then
  66                 err "Fail to get args.\n"
  67                 exit 1
  68         fi
  69
  70         # trimp arguments
  71         eval set -- ${ARGS}
  72
  73         # option dispatcher
  74         for ((i=0; i < 1000 ; i++)) do
  75                 case "$1" in
  76                         -- )
  77 #                       dbgout "param --\n"
  78                         general_param="$@"
  79                         break
  80                         ;;
  81                 easc
  82         done
  83 ```
  84
  85
  86 # proc of args.shlib
  87 ================
  88
  89     in args.shlib, it define args info like this formated string.
  90 ```
  91 usage_desc_str_syntax="
  92 prog $0 '<prog_desc>'
  93 param -<pchar> --<long-opt> ---<cmd-opt> =<value> %<pname> !<pproc> '<pdesc-str>'
  94                                                                 '<pdesc-str2>'
  95 "
  96 ```
  97     for this syntax
  98 @ pchar, short option char.
  99 @ long-opt, long option string.
 100 @ cmd-opt, sub-cmd option.
 101 @ value, paramter name string, displayed follow the option argument. if the paramter is neccisory, use []. if it is optional for this option, use <>.
 102 @ pname, paramter store paramter into this environment variable.
 103 @ pproc, process function name for this option.
 104 @ pdesc-str, describe string for this option. if the string is too long to display on console, it would be truncated to several lines to display.
 105 @ pdesc-str2, describe string continued with last option describe string. it is not the line seperator for actual display.
 106
 107     here is the example:
 108 ```
 109 usage_desc_str="
 110 prog $0 'helpertesting program'
 111 param -f --file ---file =[file_module] %<file> !<param_file> 'optional option to specify a file name that used '
 112                                                  'for processing. and this is the describe string in'
 113                                                  'second line.ÕâÀï¿ÉÒÔÊ¹ÓÃutf8×Ö·ûÏÔÊ¾£¬¿í¶È'
 114                                                  '¸ù¾ÝÖÐÎÄ×Ö·û×Ô¶¯Æ¥Åä.'
 115 param -h --help ---help = %<help> !<opt_proc_help>        'help information.'
 116 param -h --help ---help = %<help> !<opt_proc_help>        'help information.'
 117 "
 118 main ()
 119 {
 120     ProgOptDispatch "$@"
 121
 122     # todo:
 123 }
 124 ```
 125     the benifit of args.shlib is that:
 126 @ it describe option, option param, option proc function, option describe string together.
 127 @ it will be less mistake between helper description and actual code implement.
 128 @ put paramter value of option to environment variable automatically.
 129 @ invoke proc function if specified in describe string.
 130 @ display describe string is aligned automatically. event if there are char encoded by utf8.
 131     for auto-align in CJK char, the string is translatrd utf8 string to gbk string, and a gbk char is 2 byte width, so string lenth is the display width of the string. but it coast more cpu resource to do that.
 132
 133
 134 # future
 135 =======
 136
 137     the process of argument dispatch coast more cpu resource, it should be improved.
 138     argument describe string dspatch function should be improved with [[ $xx =~ xxx ]], by using regular expression. but it canbe only used In bash shell.
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167 [args³ÌÐò²ÎÊýºÍhelper]
 168
 169 # conception
 170 ==========
 171 argument: the variable for function or cmd when it is invoked.
 172 option: the string for cmd program. it is a argument string with '-' prefix, and it means that it is a function feature option for program. it is used for cmdline arguments specially.
 173 paramter: the string value followed with option arguments.
 174
 175     this three name is means the string gives to a program followed with cmd.
 176
 177
 178 # introduction
 179 ==========
 180     shell proide two cmd for cmd-opt processing, shopt and shopts. they are nearly the same, and let the program beome more easy on option processing.
 181     is there a method using txt-formated description string, to solve arguments automatically? args.shlib is used for this feature. it dispatch describe string of the shell program arguments, and resolve the arguments. it generate option flag variable if the corresponding option is used, and invoke process function it specified, with the paramter of he option.
 182
 183
 184 # example
 185 ========
 186 xxx_args_desc="
 187 |param |-l --list |---list |=<dirname> |%<listfile> |
 188 &<list_proc> |'file describe string.'
 189 |param |-h --help |--- |=[module] |%<help_info> |
 190 &<help_proc> |'help describe string.'
 191 "